home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / cug236.zip / SGREP.DOC < prev    next >
Text File  |  1980-01-02  |  9KB  |  227 lines
  1. /*
  2.     HEADER:        CUG000.00;
  3.     TITLE:        SGREP Documentation;
  4.     DATE:        05/17/1987;
  5.     VERSION:    1.0;
  6.     FILENAME:    SGREP.DOC;
  7.     SEE-ALSO:    SGREP.C;
  8.     AUTHORS:    J. McKeon;
  9. */
  10.  
  11.     SGREP is a modification of the public domain
  12. version of the Unix utility GREP, PC Sig #149 or CUG 152.
  13. The following additions were made:
  14.  
  15.     1) string substitution capability,
  16.     2) multiple pattern search,
  17.     3) distinction between upper and lower case,
  18.     4) scanning options to extend capability and speed-up processing.
  19.  
  20. All Grep options are retained except multiple files.
  21.  
  22.     The command line for Sgrep is similar to that
  23. for Grep but with the pattern replaced by the name of the
  24. pattern file. For output to the screen the command line is
  25.  
  26.     sgrep [-y] pattern_file input_file
  27.  
  28. and for output to disk,
  29.  
  30.     sgrep [-y] pattern_file input_file > output_file
  31.  
  32. The y-option removes the distinction between upper and lower case
  33. when matching patterns.
  34.  
  35.     Also included is a peprocessor using Sgrep which translates
  36. from a Basic - Fortran like language into C. Several programs are
  37. included in this "BC" language, which may also contain C statements.
  38. The pattern file, pf.bc, for this preprocessor language illustrates
  39. the use of Sgrep.
  40.  
  41.     This disk contains the following files:
  42.  
  43.     sgrep.doc    pattern matching and substitution utility
  44.     sgrep.c
  45.     pf.bc        BC to C translator
  46.     progs.bc    programs in BC
  47.     progs.c        programs translated into C by Sgrep
  48.     bc.h        small header file
  49.     bc.bat        batch file to translate and compile
  50.  
  51.     Information on the construction of patterns is contained
  52. in the help file which is displayed on typing "sgrep ?". The contents
  53. of the help file is:
  54.  
  55.                  *     *     *     *
  56.  
  57. Sgrep searches a file for a given pattern and substitutes a pattern.
  58. If no substitution is required, the command sgrep -myn corresponds
  59. to grep -n and will match only. Output is to the screen and may be
  60. re-directed using ">" at the DOS level. Execute by
  61.   sgrep [flags] pattern-file input-file
  62.  
  63. Flags are single characters preceeded by '-':
  64.    -c      Only a count of matching lines is printed.
  65.    -m      Match patterns only. No substitutions.
  66.    -n      Each line is preceeded by its line number.
  67.    -v      Only print non-matching lines.
  68.    -y      Upper and lower case match.
  69.  
  70. Each match pattern is on a separate line followed by its substitute
  71. pattern, if any, also on a separate line.
  72.  
  73.  MATCH PATTERNS
  74.  
  75. The regular_expression defines the pattern to search for.  Upper and
  76. lower-case are regarded as different unless -y option is used.
  77. x      An ordinary character (not mentioned below) matches that character.
  78. '\'    The backslash quotes any character.  "\$" matches a dollar-sign.
  79. '$'    Matches beginning or end of line.
  80. '.'    A period matches any character except "new-line".
  81. ':a'   A colon matches a class of characters described by the following
  82. ':d'     character.  ":a" matches any alphabetic, ":d" matches digits,
  83. ':n'     ":n" matches alphanumerics, ": " matches spaces, tabs, and
  84. ': '     other control characters except new-line.
  85. '*'    An expression followed by an asterisk matches zero or more
  86.        occurrances of that expression: "fo*" matches "f", "fo"
  87.        "foo", etc.
  88. '+'    An expression followed by a plus sign matches one or more
  89.        occurrances of that expression: "fo+" matches "fo", etc.
  90. '-'    An expression followed by a minus sign optionally matches
  91.        the expression.
  92. '[]'   A string enclosed in square brackets matches any character in
  93.        that string, but no others.  If the first character in the
  94.        string is a circumflex, the expression matches any character
  95.        except "new-line" and the characters in the string.  For
  96.        example, "[xyz]" matches "xx" and "zyx", while "[^xyz]"
  97.        matches "abc" but not "axb".  A range of characters may be
  98.        specified by two characters separated by "-".  Note that,
  99.        [a-z] matches alphabetics, while [z-a] never matches.
  100. The concatenation of regular expressions is a regular expression.
  101.  
  102.  SCANNING OPTIONS
  103.  
  104. The default scanning option is match all occurences of the pattern.
  105. '@'    at the beginning of the pattern, is equivalent to
  106.        "$: *", meaning match first non-whitespace pattern.
  107. '@e'   at the end of a pattern means that if a match is
  108.        found (and a substitution made), end all pattern search
  109.        on current line.
  110. '@r'   at the end of a pattern means that after a match
  111.        (and substitution), rescan line until no match occurs.
  112.  
  113.  SUBSTITUTE PATTERNS 
  114.  
  115. The only control character for substitute patterns is "?".
  116. Any other character represents itself. Only the characters ? and
  117.  \ itself need to be quoted.
  118. '?n'   where n is a non-zero digit, indicates the position where
  119.        the nth wildcard string is to be placed.
  120. A wildcard string is any string which is not completely fixed,
  121. both as to the characters and number of characters in the string.
  122.  
  123.                  *     *     *     *
  124.  
  125.     The options n, c and v are carried over from Grep and can be
  126. used only with the m (match only) option. The added y option applies
  127. to both match only and substitution.
  128.  
  129.     A substituiton file consists of 2N records, where N is the
  130. number of substitutions. The file contains N pattern pairs, each
  131. pair consisting of a match pattern followed by its substitute pattern.
  132. A match only file contains N records.
  133.  
  134.     The control characters for constructing match patterns, listed
  135.  above, are the same as those for Grep with a few changes and addtions:
  136.  
  137.     1) The beginning of line symbol "^", which also represents the
  138. complement or NCLASS operator, has been replaced by "$, now used
  139. for both beginning and end of line. When "$" is the first character in
  140. the pattern, it is a beginning of line, otherwise, it is an end of line.
  141.     2) The expressions ".", "[^x]" and ": " do not match newline (linefeed).
  142.     3) The scan options described above have been added. The @ and @e
  143. options speed-up processing. The @r option allows certain repetitve
  144. operations. For example, the standard array index designation
  145.   A[I,J,K] is changed to the C form A[I][J][K] by the pattern pair
  146.  
  147.     \[:n+,@r
  148.     [?1][
  149.  
  150. This will handle arrays of any number of dimensions. The @r scan option
  151. is also used to insert the & before each item in a list of input variables.
  152.  
  153.  
  154.     The file pf.bc is the pattern file for the BC to C translator
  155. and illustrates the use of Sgrep. The file progs.bc contains programs
  156. in the BC language with C translations in progs.c. Translation
  157. from the BC language into C is line for line to simplify
  158. error detection. While some of the substitutions could be accomplished
  159. with #define macros placed in the bc.h file, the target language would
  160. not then be standard C.
  161.  
  162.     The BC language has the following properties:
  163.  
  164.     1) Each program must begin with the line GLOBAL even if there
  165. are no global declarations.
  166.  
  167.     2) Generally, each condition or statement occupies a separate
  168. line but multiple declaration and assignment statements are possible,
  169.  
  170.     REAL A; INTEGER N
  171.     I=1; J=2; K=3
  172.  
  173.     3) No semicolons are required at the end of lines.
  174.  
  175.     4) Only lines whose first non-whitespace character is a capital
  176. letter will be processed. Other lines are copied without change. This
  177. allows C statements to be included anywhere provided the first character
  178. in the line is not a capital letter.
  179.  
  180.     5) Comments are usually on a separate line but a comment may
  181. follow a statement terminated by a semicolon,
  182.  
  183.         A = B + C;  /* Comment* /
  184.  
  185.     6) All conditions and loops must have a terminal statement,
  186.  
  187.         IF ...
  188.         ENDIF
  189.         WHILE ...
  190.         ENDWH
  191.         FOR I ...
  192.         NEXT I
  193.         etc.
  194.  
  195. The FOR statement is terminated with NEXT rather than END to increase
  196. readability.
  197.  
  198.     7) The & is inserted before variables in an input statement but
  199. a string variable must be preceded by *,
  200.  
  201.         INPUT #1, "%d %s", A, *S
  202.  
  203.     8) The file unit #n becomes file pointer fpn when used in C functions.
  204.     9) The switch ... case construction, although fairly common, has
  205. been omitted because IF ... ELSE IF ... ELSE ... ENDIF is more general
  206. and because the constructions switch, structure, typedef, #include,